[openapi3] emit additionalProperties for a declared Record indexer in 3.1 - #11954

Follow-up to #11953, which I closed as prematurely filed and wrongly framed as a bug. This is the
properly scoped version: it concedes #5961's design, narrows the claim to the case where the two
keywords are provably equivalent, and leaves sealing and composition alone.

What this changes

For OpenAPI 3.1 and 3.2, a declared Record<T> indexer is emitted as additionalProperties instead
of unevaluatedProperties, unless the model also extends another model, or the schema is sealed.
Those two keep unevaluatedProperties, because both have to account for the properties evaluated by
the sibling allOf subschema.

- const unevaluatedPropertiesSchema = shouldSeal
+ const indexerSchema = shouldSeal
    ? { not: {} }
    : this.emitter.emitTypeReference(model.indexer!.value);
- setProperty(schema, "unevaluatedProperties", unevaluatedPropertiesSchema);
+ const indexerKeyword =
+   shouldSeal || model.baseModel ? "unevaluatedProperties" : "additionalProperties";
+ setProperty(schema, indexerKeyword, indexerSchema);

model.baseModel is the same condition modelDeclaration uses to attach the allOf, so the guard
and the thing it guards against are decided by the same fact.

3.0 is untouched: schema-emitter-3-0.ts has no applyModelIndexer and uses the base
implementation, which already writes additionalProperties. 3.2 is affected, because
schema-emitter-3-2.ts extends OpenAPI31SchemaEmitter without overriding the method, and the
tests run against both.

Note Record<never> is unaffected: shouldSealSchema returns true for it, so it takes the sealing
branch and keeps unevaluatedProperties: { not: {} }.

Why: this repo cannot read its own 3.1 output

tsp-openapi3, the converter in this package, reads only additionalProperties. Of the 36 .ts
files under packages/openapi3/src/cli, zero mention unevaluatedProperties and four handle
additionalProperties (convert/generators/generate-model.ts:359,
convert/generators/generate-types.ts:482, convert/transforms/transform-component-schemas.ts:129,
convert/interfaces.ts).

So compiling model Labels is Record<string>; at 3.1 and converting the result back gives
model Labels {}. At 3.0 it gives model Labels { ...Record<string>; }. The round trip loses every
dictionary, and exits 0 while doing it. I have filed that separately, since it stands on its own
whichever way this PR goes.

Why not just keep unevaluatedProperties

I am not claiming the current behaviour is accidental. #5961 chose it on purpose and said why:

One key difference from additionalProperties though is that it evaluates properties after any
in-place applicators. [...] This is particularly useful when trying to set additionalProperties
to false on a schema that has sub-schemas.

That rationale is about composition, and it is correct. The keyword was then applied to every
declared indexer, including models that compose with nothing. This narrows it to the cases the
rationale covers.

Is it validation-equivalent where it changes?

Ajv 8.20.0 on the 2020-12 dialect, the same schema pair under each keyword, in every position this
emitter can put it:

The last row is why the guard exists. With model Ledger extends Base { ...Record<string>; } and
Base declaring id: int32, additionalProperties constrains the inherited id and the schema
rejects {"id": 1} outright.

The second row is why the guard is model.baseModel and not also a derivedModels check.
Annotations flow bottom-up, so a dictionary in branch position inside someone else's allOf behaves
identically under both keywords. A derivedModels guard would also have been non-local, because
Record<T> is a cached template instantiation shared by every use site in a program.

Coverage, and how strong it is

Because the two keywords are equivalent for a non-composing, non-never dictionary, the 3.0 document
is an oracle for the 3.1 one: the two spec versions must produce identical schemas. record.test.ts
asserts that, and asserts the two exclusions (composing models, and Record<never>) in the other
direction, so the oracle's preconditions are pinned rather than assumed.

14 tests added. I checked they are not vacuous by mutating the production code three ways and
recording which arms go red:

Every one of the 14 is killed by at least one. An earlier draft of this branch had a test asserting
that plain arrays are unaffected; it survived all three mutants, because arrays route through
arrayDeclaration/arrayLiteral and never reach applyModelIndexer at all. I removed it rather
than keep a test that cannot fail.

Shapes covered: declared indexer alone, with a base model, and as the base of other models; sealed
leaf and sealed with a base; Record<never>; a three-level chain where two levels declare an
indexer; arrays of dictionaries; nested dictionaries; cross-version parity in both directions; and
versioning, where the emitter mutates and clones the model graph, so a clone that lost its
baseModel would silently change the keyword between two versions of the same API.
openApiForVersions could not pass emitter options, so it takes them now.

Verified and unchanged, so not given new tests: merge-patch, multipart, discriminated unions, XML,
@visibility variants, and circular models.

Blast radius

packages/openapi3: 2602 tests before, 2626 after.

pnpm regen-samples and pnpm regen-specs both produce zero diff, but I want to be straight about
what that is worth: not much. All 30 checked-in sample outputs are openapi: 3.0.0 and no sample
sets openapi-versions, so the 3.1 emitter is not exercised by them; and regen-specs records the
converter snapshots, which are the opposite direction. There is no checked-in 3.1 golden output in
the repo, so the unit tests above are the real coverage. The upside is that this change causes no
golden-file churn for reviewers to read.

Worth noting that tsp init does offer an "OpenAPI 3.1 document" template, so zero golden-file churn
is not the same as zero user impact.

One case where this narrows behaviour

@extension writes arbitrary keys straight onto the schema, after applyModelIndexer has run. The
x- prefix convention is documented for @extension but not enforced, so a spec can inject an
in-place applicator that the keyword decision structurally cannot see:

@extension("allOf", #[#{ type: "object", properties: #{ flag: #{ type: "boolean" } } }])
model Dict { ...Record<string>; }

The injected allOf now sits beside additionalProperties, and an instance {"flag": true} that
validated before does not after. This also reproduces via @extension on a property.

I have pinned the current output in a test rather than guarded it, because the guard would have to
run before the extension is attached and cannot. If you would prefer applyModelIndexer to consult
getExtensions for applicator keys, say so and I will add it, but it would only cover the model
path and not the property one, which is why I did not do it unilaterally.

Why packages/json-schema is not in this PR

#5961 changed both emitters in one changeset, so leaving one behind is a fair thing to ask about. I
looked, and a mechanical port would make things worse rather than better:

• openapi3 classifies Record<never> through shouldSealSchema/isNeverType. json-schema has no
  such check and reaches { not: {} } through the indexer path instead. Applying the same guard
  there would flip Record<never> to additionalProperties in json-schema while openapi3 keeps
  unevaluatedProperties, creating a divergence rather than removing one.
• json-schema decides its allOf with model.baseModel && !shouldInlineBase, where the second
  term covers discriminated-union inlining that openapi3 does not have.

So aligning the two is a decision about both emitters and I would rather you made it than have me
assume it. Happy to extend this PR, or follow up separately, whichever you prefer.

Notes

• Changeset filed as feature, matching OpenAPI/JsonSchema - use unevaluatedProperties instead of additionalProperties and support setting to false #5961, which shipped the original change that way.
• openapi-typescript also does not implement unevaluatedProperties and renders a dictionary as
  Record<string, never>, discarding the declared value type. That is tracked on their side as
  Support for unevaluatedProperties openapi-ts/openapi-typescript#2839 and is a real gap there, not only here. I mention it as evidence
  about ecosystem support rather than as a defect report against this repo.
• If you would rather this sat behind an emitter option, or went through a design issue first, say so
  and I will rework it. The diff is one method, so either is cheap.